home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib.fmt / tcl / Fork.man < prev    next >
Encoding:
Text File  |  1992-11-10  |  9.4 KB  |  199 lines
  1.  
  2.  
  3.  
  4. Tcl_Fork              C Library Procedures               Tcl_Fork
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NNAAMMEE                                                               |
  11.      Tcl_Fork,  Tcl_WaitPids,  Tcl_DetachPids  -   manage   child  |
  12.      processes                                                     |
  13.  
  14. SSYYNNOOPPSSIISS                                                           |
  15.      ##iinncclluuddee <<ttccll..hh>>                                              |
  16.  
  17.      int                                                           |
  18.      TTccll__FFoorrkk( )                                                   |
  19.  
  20.      int                                                           |
  21.      TTccll__WWaaiittPPiiddss(_n_u_m_P_i_d_s, _p_i_d_P_t_r, _s_t_a_t_u_s_P_t_r)                      |
  22.  
  23.      int                                                           |
  24.      TTccll__DDeettaacchhPPiiddss(_n_u_m_P_i_d_s, _p_i_d_P_t_r)                               |
  25.  
  26. AARRGGUUMMEENNTTSS                                                          |
  27.      int   _n_u_m_P_i_d_s      (in)                                            ||
  28.                                   Number of process ids contained  |
  29.                                   in  the  array  pointed  to  by  |
  30.                                   _p_i_d_P_t_r.                          |
  31.  
  32.      int   *_p_i_d_P_t_r      (in)                                            ||
  33.                                   Address   of  array  containing  |
  34.                                   _n_u_m_P_i_d_s process ids.             |
  35.  
  36.      int   *_s_t_a_t_u_s_P_t_r   (out)                                           ||
  37.                                   Address   of   place  to  store  |
  38.                                   status       returned        by  |
  39.                                   exited/suspended process.        |
  40. _________________________________________________________________  |
  41.  
  42.  
  43. DDEESSCCRRIIPPTTIIOONN                                                        |
  44.      These procedures keep track of child processes in  order  to  |
  45.      make  it  easier for one application to manage several chil-  |
  46.      dren.  If an application uses the UNIX _f_o_r_k and _w_a_i_t  kernel  |
  47.      calls  directly,  problems occur in situations like the fol-  |
  48.      lowing:                                                       |
  49.  
  50.      [1]                                                                ||
  51.           One  part of an application creates child C1.  It plans  |
  52.           to let the child run in background, then later wait for  |
  53.           it to complete.                                          |
  54.  
  55.      [2]                                                                ||
  56.           Some  other  part  of  the  application creates another  |
  57.           child C2, not knowing anything about C1.                 |
  58.  
  59.      [3]                                                                ||
  60.  
  61.  
  62.  
  63. Sprite v1.0                                                     1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. Tcl_Fork              C Library Procedures               Tcl_Fork
  71.  
  72.  
  73.  
  74.           The  second  part  of the application uses _w_a_i_t to wait  |
  75.           for C2 to complete.                                      |
  76.  
  77.      [4]                                                                ||
  78.           C1  completes  before C2, so C1 is returned by the _w_a_i_t  |
  79.           kernel call.                                             |
  80.  
  81.      [5]                                                                ||
  82.           The  second  part  of the application doesn't recognize  |
  83.           C1, so it ignores it and calls _w_a_i_t again.   This  time  |
  84.           C2 completes.                                            |
  85.  
  86.      [6]                                                                ||
  87.           The first part of the application eventually decides to  |
  88.           wait for its child to complete.   When  it  calls  _w_a_i_t  |
  89.           there  are  no  children left, so _w_a_i_t returns an error  |
  90.           and the application never  gets  to  examine  the  exit  |
  91.           status for C1.                                           |
  92.  
  93.      The procedures TTccll__FFoorrkk,  TTccll__WWaaiittPPiiddss,  and  TTccll__DDeettaacchhPPiiddss  |
  94.      get  around  this  problem  by  keeping  a  table  of  child  |
  95.      processes and their exit statuses.  They also provide a more  |
  96.      flexible  waiting mechanism than the _w_a_i_t kernel call.  Tcl-  |
  97.      based applications should never call _f_o_r_k and _w_a_i_t directly;  |
  98.      they should use TTccll__FFoorrkk, TTccll__WWaaiittPPiiddss, and TTccll__DDeettaacchhPPiiddss.   |
  99.  
  100.      TTccll__FFoorrkk calls _f_o_r_k and returns the result of the _f_o_r_k  ker-  |
  101.      nel  call.   If  the  _f_o_r_k call was successful then TTccll__FFoorrkk  |
  102.      also enters the new process into its internal table of child  |
  103.      proceses.   If  _f_o_r_k  returns an error then TTccll__FFoorrkk returns  |
  104.      that same error.                                              |
  105.  
  106.      TTccll__WWaaiittPPiiddss  calls  _w_a_i_t  repeatedly  until  one   of   the  |
  107.      processes  in  the _p_i_d_P_t_r array has exited or been killed or  |
  108.      suspended by  a  signal.   When  this  occurs,  TTccll__WWaaiittPPiiddss  |
  109.      returns  the  process  identifier for the process and stores  |
  110.      its wait status at *_s_t_a_t_u_s_P_t_r.  If  the  process  no  longer  |
  111.      exists   (it  exited  or  was  killed  by  a  signal),  then  |
  112.      TTccll__WWaaiittPPiiddss removes its entry  from  the  internal  process  |
  113.      table.   If  _w_a_i_t returns a process that isn't in the _p_i_d_P_t_r  |
  114.      array, TTccll__WWaaiittPPiiddss saves its wait status  in  the  internal  |
  115.      process table and calls _w_a_i_t again.  If one of the processes  |
  116.      in the _p_i_d_P_t_r array has already exited (or suspended or been  |
  117.      killed)  when  TTccll__WWaaiittPPiiddss  is called, that process and its  |
  118.      wait status are returned immediately without calling _w_a_i_t.    |
  119.  
  120.      TTccll__WWaaiittPPiiddss provides  two  advantages.   First,  it  allows  |
  121.      processes  to  exit  in any order, and saves their wait sta-  |
  122.      tuses.  Second, it allows waiting on a number  of  processes  |
  123.      simultaneously,  returning  when  any  of  the  processes is  |
  124.      returned by _w_a_i_t.                                             |
  125.  
  126.  
  127.  
  128.  
  129. Sprite v1.0                                                     2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. Tcl_Fork              C Library Procedures               Tcl_Fork
  137.  
  138.  
  139.  
  140.      TTccll__DDeettaacchhPPiiddss is used to indicate that the  application  no  |
  141.      longer  cares  about the processes given by the _p_i_d_P_t_r array  |
  142.      and will never use TTccll__WWaaiittPPiiddss  to  wait  for  them.   This  |
  143.      occurs,  for example, if one or more children are to be exe-  |
  144.      cuted in background and the parent doesn't care whether they  |
  145.      complete  successfully.   When TTccll__DDeettaacchhPPiiddss is called, the  |
  146.      internal process table entries for the processes are  marked  |
  147.      so that the entries will be removed as soon as the processes  |
  148.      exit or are killed.                                           |
  149.  
  150.      If none of the pids passed to  TTccll__WWaaiittPPiiddss  exists  in  the  |
  151.      internal process table, then -1 is returned and _e_r_r_n_o is set  |
  152.      to ECHILD.  If a _w_a_i_t kernel call  returns  an  error,  then  |
  153.      TTccll__WWaaiittPPiiddss returns that same error.  If a _w_a_i_t kernel call  |
  154.      returns a process that isn't in the internal process  table,  |
  155.      TTccll__WWaaiittPPiiddss  panics  and  aborts  the application.  If this  |
  156.      situation occurs, it means that a process has  been  created  |
  157.      without  calling  TTccll__FFoorrkk and that its exit status is about  |
  158.      to be lost.                                                   |
  159.  
  160.      TTccll__WWaaiittPPiiddss defines wait statuses to have type  _i_n_t,  which  |
  161.      is  correct  for  POSIX and many variants of UNIX. Some BSD-  |
  162.      based UNIX systems still use type _u_n_i_o_n _w_a_i_t for  wait  sta-  |
  163.      tuses;   it should be safe to cast a pointer to a _u_n_i_o_n _w_a_i_t  |
  164.      structure to (_i_n_t *) before passing it to TTccll__WWaaiittPPiiddss as in  |
  165.      the following code:                                           |
  166.  
  167.           uunniioonn wwaaiitt ssttaattuuss;;                                       |
  168.           iinntt ppiidd11,, ppiidd22;;                                          |
  169.           ......                                                      |
  170.           ppiidd22 == TTccll__WWaaiittPPiiddss((11,, &&ppiidd11,, ((iinntt **)) &&ssttaattuuss));;          |
  171.  
  172.  
  173. KKEEYYWWOORRDDSS                                                           |
  174.      background, child, detach, fork, process, status, wait
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195. Sprite v1.0                                                     3
  196.  
  197.  
  198.  
  199.